Crate envmnt

Expand description

envmnt

Environment variables utility functions.

This library has many helper functions to access/modify/check environment variables.

Examples

Get/Set/Remove environment variables

use envmnt::{ExpandOptions, ExpansionType};

fn main() {
    if !envmnt::exists("MY_ENV_VAR") {
        envmnt::set("MY_ENV_VAR", "SOME VALUE");
    }

    let mut value = envmnt::get_or("MY_ENV_VAR", "DEFAULT_VALUE");
    println!("Env Value: {}", &value);

    value = envmnt::get_or_panic("MY_ENV_VAR");
    println!("Env Value: {}", &value);

    let pre_value = envmnt::get_set("MY_ENV_VAR", "SOME NEW VALUE");

    let value = envmnt::get_or("MY_ENV_VAR", "DEFAULT_VALUE");
    println!("New Env Value: {}", &value);
    println!("Previous Env Value: {:?}", &pre_value);

    let var_was_set = envmnt::set_optional("MY_ENV_VAR", &Some("OPTIONAL VALUE"));
    println!("Env Was Modified: {}", var_was_set);

    let all_vars = envmnt::vars(); // returned as Vec<(String, String)>

    for (key, value) in all_vars {
        println!("{}: {}", key, value);
    }

    envmnt::set("MY_ENV_VAR2", "SOME VALUE2");

    let value = envmnt::get_any(&vec!["MY_ENV_VAR1", "MY_ENV_VAR2"], "default");
    println!("MY_ENV_VAR1 exists: {}", envmnt::exists("MY_ENV_VAR1"));
    println!("MY_ENV_VAR2 exists: {}", envmnt::exists("MY_ENV_VAR2"));
    println!("Found value: {}", value);

    let mut options = ExpandOptions::new();
    options.expansion_type = Some(ExpansionType::Unix);
    let mut value = envmnt::expand("Env: MY_ENV value is: ${MY_ENV}", Some(options));
    println!("Expanded: {}", &value);
    options.expansion_type = Some(ExpansionType::UnixBracketsWithDefaults);
    value = envmnt::expand(
        "Env: MY_ENV_NOT_FOUND value is: ${MY_ENV_NOT_FOUND:default value}",
        Some(options),
    );
    println!("Expanded: {}", &value);
}

Get/Set boolean environment variables and other comparisons

fn main() {
    envmnt::set_bool("FLAG_VAR", true);
    let mut flag_value = envmnt::is_or("FLAG_VAR", false);
    println!("Bool Flag: {}", &flag_value);

    flag_value = envmnt::is("FLAG_VAR");
    assert!(flag_value);

    envmnt::set_bool("FLAG_VAR", true);
    assert!(envmnt::is_equal("FLAG_VAR", "true"));

    envmnt::set("MY_ENV_VAR", "SOME VALUE");
    let same = envmnt::is_equal("MY_ENV_VAR", "SOME VALUE");
    println!("Value Is Same: {}", &same);
    let mut contains = envmnt::contains("MY_ENV_VAR", "_ENV_");
    println!("Value Contained: {}", &contains);
    contains = envmnt::contains_ignore_case("MY_ENV_VAR", "_env_");
    println!("Value Contained (case insensitive): {}", &contains);
}

Get/Set numeric environment variables

fn main() {
    // all numeric data types: u8/i8/u16/i16/u32/i32/u64/i64/u128/i128/f32/f64/isize/usize
    // are supported by specific set/get functions.
    envmnt::set_u8("U8_TEST_ENV", 50);
    let mut value_u8 = envmnt::get_u8("U8_TEST_ENV", 5);
    println!("u8 value: {}", value_u8);

    envmnt::set_isize("ISIZE_TEST_ENV", -50);
    let mut value_isize = envmnt::get_isize("ISIZE_TEST_ENV", 5);
    println!("isize value: {}", value_isize);

    // increment/decrement values
    value_isize = envmnt::increment("U8_TEST_ENV");
    assert_eq!(value_isize, 51);
    value_u8 = envmnt::get_u8("U8_TEST_ENV", 5);
    assert_eq!(value_u8, 51);
    value_isize = envmnt::decrement("U8_TEST_ENV");
    assert_eq!(value_isize, 50);
    value_u8 = envmnt::get_u8("U8_TEST_ENV", 5);
    assert_eq!(value_u8, 50);
}

Get and parse any type T that implements FromStr

fn main() {
    envmnt::set("ENV_VAR", "123");

    let value: i16 = envmnt::get_parse("ENV_VAR").unwrap();
    assert_eq!(value, 123);

    let value: String = envmnt::get_parse("ENV_VAR").unwrap();
    assert_eq!(value, "123");

    let value: i32 = envmnt::get_parse_or("ENV_VAR", 123).unwrap();
    assert_eq!(value, 123);

    let value: i64 = envmnt::get_parse_or("ENV_UNDEFINED", 321).unwrap();
    assert_eq!(value, 321);
}

Get/Set list environment variables

fn main() {
    envmnt::set_list(
        "LIST_TEST_ENV",
        &vec!["1".to_string(), "2".to_string(), "3".to_string()],
    );

    let mut values = envmnt::get_list("LIST_TEST_ENV").unwrap();
    println!("List Values: {:?}", values);

    let mut same = envmnt::is_equal("LIST_TEST_ENV", "1;2;3");
    println!("Same: {}", same);

    let mut options = envmnt::ListOptions::new();
    options.separator = Some(",".to_string());
    envmnt::set_list_with_options(
        "LIST_TEST_ENV",
        &vec!["1".to_string(), "2".to_string(), "3".to_string()],
        &options,
    );

    values = envmnt::get_list_with_options("LIST_TEST_ENV", &options).unwrap();
    println!("List Values: {:?}", values);

    same = envmnt::is_equal("LIST_TEST_ENV", "1,2,3");
    println!("Same: {}", same);
}

Bulk Operations

use indexmap::IndexMap;

fn main() {
    let mut env: IndexMap<String, String> = IndexMap::new();
    env.insert("ENV_VAR1".to_string(), "MY VALUE".to_string());
    env.insert("ENV_VAR2".to_string(), "MY VALUE2".to_string());

    envmnt::set_all(&env);

    let value = envmnt::get_or_panic("ENV_VAR1");
    println!("Value Is: {}", &value);

    let mut found = envmnt::is_any_exists(&vec!["ENV_VAR1", "ENV_VAR2"]);

    println!("Any Found: {}", &found);

    found = envmnt::is_all_exists(&vec!["ENV_VAR1", "ENV_VAR2"]);

    println!("All Found: {}", &found);

    envmnt::remove_all(&vec!["ENV_VAR1", "ENV_VAR2"]);

    found = envmnt::is_any_exists(&vec!["ENV_VAR1", "ENV_VAR2"]);

    println!("Any Found: {}", &found);

    env = IndexMap::new();
    env.insert("ENV_VAR1".to_string(), "MY VALUE".to_string());
    env.insert("ENV_VAR2".to_string(), "MY VALUE2".to_string());

    let eval_env = |key: String, value: String| {
        let mut updated_key = String::from("KEY-");
        updated_key.push_str(&key);
        let mut updated_value = String::from("VALUE-");
        updated_value.push_str(&value);
        Some((updated_key, updated_value))
    };

    envmnt::evaluate_and_set_all(&env, eval_env);

    let value = envmnt::get_or_panic("KEY-ENV_VAR1");
    println!("Value Is: {}", &value);
}

File Operations

fn main() {
    let mut output = envmnt::load_file("./src/test/var.env");
    assert!(output.is_ok());

    let eval_env = |key: String, value: String| {
        let mut updated_value = String::from("PREFIX-");
        updated_value.push_str(&value);
        Some((key, updated_value))
    };

    output = envmnt::evaluate_and_load_file("./src/test/var.env", eval_env);
    assert!(output.is_ok());
}

Installation

In order to use this library, just add it as a dependency:

[dependencies]
envmnt = "*"

License

Developed by Sagie Gur-Ari and licensed under the Apache 2 open source license.

Create a new checkpoint, for the current environment of the process, at a later date a checkpoint can be restored using [Checkpoint::restore], which will rollback the environment to all values present at the time this function was called.

contains

Returns true if the provided environment variable is defined and contains the provided value.

contains_ignore_case

Returns true if the provided environment variable is defined and contains the provided value regardless of the case.

decrement

Decrements and returns the new value stored by the given environment variable key. In case the variable does not exist, it will decrement to -1. The updated value will be returned.

evaluate_and_load_file

Parses the provided env file and loads all environment variables.

evaluate_and_set_all

Sets all the provided env key/value pairs.

exists

Returns true environment variable is defined.

expand

Expands the provided string value by replacing the environment variables defined in it. The syntax of the environment variables is based on the type requested.

get_any

Returns the first environment variable found.

get_f32

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_f64

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_i8

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_i16

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_i32

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_i64

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_i128

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_isize

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_list

Returns the requested environment variable as a string vector.

get_list_with_options

Returns the requested environment variable as a string vector.

get_or

Returns the environment variable value or if is not defined, the default value will be returned.

get_or_panic

Returns the environment variable value. If the variable is not defined, this function will panic.

get_parse

Returns the parsed environment variable value.

get_parse_or

Returns the parsed environment variable value or if is not defined, the default value will be returned.

get_remove

Removes the provided environment variable and returns its previous value (if any).

get_set

Sets the environment variable value and returns the previous value.

get_u8

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_u16

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_u32

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_u64

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_u128

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

get_usize

Returns the environment variable value or a default value in case the variable is not defined or cannot be parsed.

increment

Increments and returns the new value stored by the given environment variable key. In case the variable does not exist, it will increment to 1. The updated value will be returned.

is

Returns false if environment variable value if falsy. The value is falsy if it is one of the following:

is_all_exists

Returns true if all of environment variables are defined.

is_any_exists

Returns true if any of environment variables is defined.

is_equal

Returns true if the provided environment variable is defined and equals the provided value.

is_or

Returns false if environment variable value if falsy.
Any other value is returned as true.
The value is falsy if it is one of the following:

load_file

Parses the provided env file and loads all environment variables.